home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / icomblt5.zip / REPLACE.DOC < prev    next >
Text File  |  1986-07-07  |  12KB  |  361 lines
  1.    REPLACE 3.0                                                  July 1, 1986
  2.  
  3.  
  4.    DESCRIPTION:
  5.    ===========
  6.  
  7.    REPLACE  is a general purpose MS-DOS filter that reads a sequential input
  8.    file, replaces specified strings with new strings, and writes the  result
  9.    to  a new sequential file.  It reads the input file from standard in, and
  10.    sends the output file to standard out.  This allows it to  be  used  with
  11.    MS-DOS  piping.   It  is  driven  by  a control file and produces a small
  12.    report of statistics  or  errors  back  to  the  standard  error  device,
  13.    normally  the terminal.  It supports both character and hex input for the
  14.    old and new strings. 
  15.  
  16.    (C) Copyright 1986 by Bill Prew, ALL RIGHTS RESERVED
  17.  
  18.    Please refer all inquiries to:
  19.        Bill Prew
  20.        1615 Pawtucket Ave
  21.        Rumford RI 02916
  22.  
  23.  
  24.    You may copy and distribute this program freely, provided that:
  25.        <1> No fee is charged for such copying and distribution, and
  26.        <2> It is distributed ONLY in its original, unmodified state.
  27.  
  28.    This program is being distributed as user  supported  software.   If  you
  29.    like  this  program,  and  find it of use, then your contribution will be
  30.    appreciated.  If you are using this product in a commercial  environment,
  31.    then the contribution is not voluntary.  If you would like the source for
  32.    the  program  send a mailer and $10 to the address above with a formatted
  33.    floppy. 
  34.  
  35.  
  36.    USAGE:
  37.    =====
  38.    The command format to execute the program is;
  39.  
  40.    REPLACE <input-filename >output-filename control-filename
  41.  
  42.    where input-filename is the input  file,  output-filename  is  the  newly
  43.    created   file   after  all  replace  commands  have  been  applied,  and
  44.    control-filename is the name  of  the  file  that  contains  the  replace
  45.    commands and options. 
  46.  
  47.  
  48.    CONTROL CARD FORMATS:
  49.    ====================
  50.    The general format of the control cards is;
  51.  
  52.    type,parms
  53.  
  54.    where  type  can be "opts", "text" or "hex" as discussed below, and parms
  55.    are different parameters and information needed by the different  control
  56.    cards. 
  57.  
  58.  
  59.  
  60.                                     Page 1                                  
  61.    REPLACE 3.0                                                  July 1, 1986
  62.  
  63.  
  64.        "OPTS" CONTROL CARD:
  65.        -------------------
  66.        This card selects several options for the run with the format;
  67.  
  68.        opts,[pad | nopad , one | all]
  69.  
  70.        pad ............... this  preserves  trailing  spaces  in  the output
  71.                            records. 
  72.  
  73.        nopad ............. this causes all trailing spaces to be  eliminated
  74.                            from  the  output records before they are written
  75.                            (this is the default). 
  76.  
  77.        one ............... this option  forces  the  program  to  only  scan
  78.                            forward   on  the  line  after  each  replace  is
  79.                            performed. 
  80.  
  81.        all ............... this causes the  entire  line  to  be  re-scanned
  82.                            after  each  replace  is  performed  (this is the
  83.                            default). 
  84.  
  85.  
  86.        "TEXT" CONTROL CARD:
  87.        --------------------
  88.        This is the most used card in replace control files and specifies  an
  89.        old  string  to  be  replaced  by  a  new string.  The strings can be
  90.        different lengths and the new string can be a 'null' string to  cause
  91.        deletion of the old string.  The format is;
  92.  
  93.        text,'old-string'[new-string]'
  94.  
  95.        ' ................. notice  the  three  single  quotes  in the parms.
  96.                            this is the delimiter and bounds the new and  old
  97.                            strings.  it can be any character, as long as all
  98.                            three are the same. 
  99.  
  100.        old-string ........ this is the target string you want to replace. 
  101.  
  102.        new-string ........ this  is  new  string  to  substitute for the old
  103.                            string.   if  omitted  the  old  string  will  be
  104.                            deleted. 
  105.  
  106.  
  107.        "HEX" CONTROL CARD:
  108.        -------------------
  109.        This  card is very similar to the "text" card except it allows you to
  110.        specify the old and new strings as hex data.  The format is;
  111.  
  112.        hex,old-hex-string,[new-hex-string]
  113.  
  114.        old-hex-string .... this is the target string you want to replace, in
  115.                            hex format.  for example 414243 would replace ABC
  116.                            in the input file. 
  117.  
  118.  
  119.  
  120.                                     Page 2                                  
  121.    REPLACE 3.0                                                  July 1, 1986
  122.  
  123.  
  124.        new-hex-string .... this is new string  to  substitute  for  the  old
  125.                            string  in hex format.  if omitted the old string
  126.                            will be deleted. 
  127.  
  128.  
  129.    EXAMPLES:
  130.    =========
  131.  
  132.        EXAMPLE 1:
  133.        ----------
  134.  
  135.            REPLACE <in >out replace.ctl
  136.  
  137.            replace.ctl ....... text,'XXXX'YYYY'
  138.                                text,'ZZZZ''
  139.                                hex,30,2d
  140.  
  141.            in ................ 0123456789
  142.                                XXXXXXXX
  143.                                XXXXZZZZ
  144.  
  145.            out ............... -123456789
  146.                                YYYYYYYY
  147.                                YYYY
  148.  
  149.        This is pretty straight forward, all "XXXX" were replaced by  "YYYY",
  150.        all "ZZZZ" were deleted, and hex "30" was replaced by "2d". 
  151.  
  152.        EXAMPLE 2:
  153.        ----------
  154.  
  155.            REPLACE <in >out replace.ctl
  156.  
  157.            replace.ctl ....... opts,all
  158.                                text,'XXXX'YYXX'
  159.  
  160.            in ................ XXXXXXXX
  161.  
  162.            out ............... YYYYYYXX
  163.  
  164.        This  is a little trickier.  I have shown the "opts,all" for clarity,
  165.        even though the same results would occur if it was left out, as it is
  166.        the default.  Notice that the line was transformed from "XXXXXXXX" to
  167.        "YYYYYYXX" as below;
  168.  
  169.        "XXXXXXX" -> "YYXXXXXX" -> "YYYYXXXX" -> "YYYYYYXX"
  170.  
  171.        This illustrates how the entire line is re-scanned after each replace
  172.        is performed.  The next example contrasts this with the "one" option. 
  173.  
  174.        EXAMPLE 3:
  175.        ----------
  176.  
  177.            REPLACE <in >out replace.ctl
  178.  
  179.  
  180.                                     Page 3                                  
  181.    REPLACE 3.0                                                  July 1, 1986
  182.  
  183.  
  184.            replace.ctl ....... opts,one
  185.                                text,'XXXX'YYXX'
  186.  
  187.            in ................ XXXXXXXX
  188.  
  189.            out ............... YYXXYYXX
  190.  
  191.        Notice that the results here are different since only  the  remaining
  192.        part  of  the line is re-scanned after each replace.  Notice that the
  193.        line was transformed from "XXXXXXXX" to "YYXXYYXX" as below;
  194.  
  195.        "XXXXXXX" -> "YYXXXXXX" -> "YYXXYYXX"
  196.  
  197.        EXAMPLE 4:
  198.        ----------
  199.  
  200.            FILATR a: | REPLACE >out replace.ctl
  201.  
  202.            replace.ctl ....... text,' A ' Modified, '
  203.                                text,' S ' System, '
  204.                                text,' R ' Read-only, '
  205.                                text,' H ' Hidden, '
  206.                                text,' .''
  207.  
  208.            FILATR output ..... MS-DOS File Attribute Utility version 2.12
  209.                                 
  210.                                loader.sys           . S R H .
  211.                                io.sys               . S R H .
  212.                                msdos.sys            . S R H .
  213.                                command.com          . . . . .
  214.                                config.sys           A . . . .
  215.                                autoexec.bat         . . . . .
  216.                                 
  217.                                6 files
  218.  
  219.            out ............... MS-DOS File Attribute Utility version 2.12
  220.                                 
  221.                                loader.sys           System, Read-only, Hidden,
  222.                                io.sys               System, Read-only, Hidden,
  223.                                msdos.sys            System, Read-only, Hidden,
  224.                                command.com
  225.                                config.sys           Modified,
  226.                                autoexec.bat
  227.                                 
  228.                                6 files
  229.  
  230.        This example demonstrates the support of piping to  pass  the  output
  231.        from one command into the REPLACE program. 
  232.  
  233.  
  234.    NOTES:
  235.    =====
  236.        <1>  Each  record  from  the  input  file  is read once, and then all
  237.        replaces are applied to it, in the order they  were  specified.   The
  238.  
  239.  
  240.                                     Page 4                                  
  241.    REPLACE 3.0                                                  July 1, 1986
  242.  
  243.  
  244.        order  of  the  control cards can be very important if the results of
  245.        one replace affect another one. 
  246.  
  247.        <2> The replace procedure is recursive  in  nature  so  that  when  a
  248.        record  is  read,  and  a  change applied, the changed record is then
  249.        checked to see if another change is required (starting at  the  first
  250.        position  of the record).  if the all option is active, or picking up
  251.        at the end of the replaced string if the one option is active). 
  252.  
  253.        <3> By using 'con' (without the quotes) as  the  control-filename  on
  254.        the  command  line  you can enter the control cards from the keyboard
  255.        and terminate them with a ctl-Z.  This is  convenient  for  one  time
  256.        quicky runs. 
  257.  
  258.  
  259.    LIMITS:
  260.    ======
  261.        Maximum input/output record length = 2000 bytes
  262.  
  263.        Maximum number of control cards = 100
  264.  
  265.        Maximum length of strings on 'text'/'hex' control cards = 100 bytes
  266.  
  267.        Binary  data  is  supported with the exception of line-feed chars, as
  268.        these are used as in MS-DOS to end logical records in the  sequential
  269.        file. 
  270.  
  271.  
  272.    RELEASE INFO:
  273.    ============
  274.  
  275.    RELEASE 3.0
  276.  
  277.        <1> The  program  was completely re-written using Lattice version 3.0
  278.        for speed and added flexibility.  This release runs  3  to  10  times
  279.        faster than release 2.0. 
  280.  
  281.        <2> The  program was changed to support MS-DOS redirection and piping
  282.        for it's input and output filenames.  It now reads  it's  input  from
  283.        Standard Input and writes it's output to Standard Output. 
  284.  
  285.        <3> The  program now supports record lengths up to 2000 characters in
  286.        length. 
  287.  
  288.        <4> The control  card  format  was  changed  slightly  to  allow  any
  289.        character  to  be  used  as  the  text string delimiter.  This allows
  290.        double quotes to be part of the replace strings by using  some  other
  291.        delimiter character. 
  292.  
  293.        <5> An  option  switch  was  added  to  allow  specify 'one' or 'all'
  294.        replace modes.  See the detail documentation for further info. 
  295.  
  296.    RELEASE 2.0
  297.  
  298.  
  299.  
  300.                                     Page 5                                  
  301.    REPLACE 3.0                                                  July 1, 1986
  302.  
  303.  
  304.        <1> The statistics are now displayed directly to the  screen  instead
  305.        of being written to the REPLACE.PRN file. 
  306.  
  307.        <2> The  control  file  name  no  longer  has to be REPLACE.CTL.  Any
  308.        filename can  be  entered  on  the  command  line  such  as  "REPLACE
  309.        TEST.CTL".   If  no  name  is  entered,  REPLACE.CTL is still used by
  310.        default. 
  311.  
  312.        <3> The program has been re-written a bit and now runs in almost half
  313.        the time of the initial version. 
  314.  
  315.        <4> Error reporting has been greatly improved. 
  316.  
  317.        <5> A check is made to determine if the replacement  string  contains
  318.        the source string.  This eliminates the chance of an infinite loop. 
  319.  
  320.    RELEASE 1.0
  321.  
  322.        <1> This was the initial release. 
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                                     Page 6                                  
  361.